WRP  Technical  Note  HS-CP-5.1 

May  1994 

Userguide  for  the  Wetland  Water 
Budget  Model  Tutorial 


PURPOSE:  This  technical  note  provides  step-by-step  instructions  for  using  a  computerized  tutorial  to 
help  set  up,  execute,  and  calibrate  the  Wetland  Water  Budget  Model,  and  to  help  manipulate  the 
model’s  output  using  a  post-processing  program. 

BACKGROUND:  The  Wedands  Research  Program  has  developed  a  water  budget  model  which  can 
be  used  to  model  hydrologic  and  hydraulic  processes  in  wetlands,  and  is  a  useful  tool  for  investigating 
wetland  functions.  The  model  is  modular  in  design,  allowing  users  to  run  only  those  modules 
important  to  their  study.  For  example,  if  users  are  interested  in  surface  water  processes,  they  would 
run  the  surface  water  module.  The  model  also  has  a  horizontal  groundwater  flow  module  and  a 
vertical  processes  module  (for  precipitation,  canopy  interception,  infiltration,  and  evapotranspiration). 
Any  combination  of  the  modules  can  be  selected  by  the  user.  The  number  of  input  files  (and  the 
amount  of  data)  needed  to  run  the  model  depends  on  which  modules  are  selected.  A  user  could 
quickly  become  confused  over  which  input  files  are  needed  and  what  data  are  required.  To  eliminate 
the  confusion,  a  screen-driven,  PC-based  tutorial  was  developed  to  help  users  select  modules,  identify 
all  of  the  necessary  input  files,  and  to  give  users  instructions  for  formatting  the  data  in  those  input 
files.  The  program  also  provides  instructions  for  calibrating  and  running  the  water  budget  model,  and 
manipulating  the  model’s  output. 

For  more  information  about  the  water  budget  model  (including  the  processes  it  models,  applications 
of  the  model,  and  assessments  of  the  model’s  capabilities),  the  tutorial  program  and  a  program  for 
manipulating  output  data,  see  Walton  and  Chapman  (1993). 

OVERVIEW:  The  computerized  tutorial  for  running  the  water  budget  model  uses  a  sequence  of 
screens  to  prompt  users  for  information  they  need  for  their  particular  model  application.  The 
following  is  an  overview  of  the  screens. 

SCREEN  1:  Provides  instructions  for  using  the  screens.  To  move  the  cursor  around  a  screen,  use 
the  TAB  or  ARROW  keys.  To  move  from  one  screen  to  the  next,  use  the  Page  Up/Down  keys. 
Use  the  Enter  key  to  make  selections  within  screens  and  the  ControIH  keys ‘to  obtain  "Help"  at  any 
time. 

SCREEN  2:  Permits  users  to  select  one  or  more  of  the  water  budget  model’s  modules  for  their 
particular  application,  and  allows  them  to  define  a  project  name  (less  than  9  characters)  which 
becomes  the  "root"  name  for  all  of  the  input  and  output  files. 

SCREEN  3:  Identifies  the  necessary  input  files  required  for  the  particular  application  (set  of 
modules)  selected  by  the  user.  The  necessary  files  are  indicated  by  a  "YES"  appearing  in  the  box 
next  to  the  file  name.  Users  can  view  examples  of  the  format  for  a  file’s  data  by  selecting  (Enter 
key)  the  file  while  the  cursor  is  positioned  by  the  file  name.  The  user  can  also  get  more  information 
regarding  data  sources  by  pressing  the  Control_D  keys.  The  names  of  the  output  files  that  the  water 
budget  model  will  generate  are  identified  by  the  word  "OUT"  next  to  the  file  name.  The  "MAKE 
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FILE"  option  will  automatically  generate  a  file  list  (called  "root")  which  the  water  budget  model  uses 
to  identify  which  files  are  input  files  and  which  are  output  files. 

SCREEN  4:  Tells  the  user  how  to  setup  the  input  data,  calibrate  and  run  the  model,  and  manipulate 
die  output  data.  When  the  user  exits  this  screen,  the  tutorial  ends.  The  user  may  also  exit  the 
tutorial  at  any  time  by  pressing  the  END  key. 

The  remainder  of  this  TN  concentrates  on  the  module  components  of  the  tutorial. 


SURFACE  WATER  MODULE  SELECTION:  By  selecting  the  surface  water  module  (from  SCREEN 
2)  for  their  model  application,  users  can  simulate  surface  water  processes  such  as  channel  flow,  over¬ 
bank  wetting  and  drying,  remote-basin  inflow,  tidal  forcing,  local  rainfall  and  wind  forcing. 
SCREEN  3  of  the  program  will  enable  the  following  tile  names  (i.e.  a  "YES"  will  appear  next  to  the 
file  names  in  SCREEN  3): 


root.OUT 
root. PAR 

root.GRD 

root.ELV 

root.PRP 


root.INI 

root.BCI 

root.HBC 

root.FBC 

root. MET 

root.HDS 
root  .FLO 
root.VOL 
root.VEL 


general  output  file  to  which  model  input  and  run  information  are  output. 

run  parameter  file  where  module  selection;  simulation  start  date,  duration,  time  step; 
print  initiation  and  interval;  and  echo  print  options  are  given. 

grid  file  where  the  number,  location,  size,  and  shape  of  nodes  and  links;  the  linkage 
between  nodes;  and  link  elevation,  inverse  side  slope,  and  type  are  defined. 

contains  the  bottom  and  overbank  elevations  of  each  node. 

defines  link  properties  such  as  friction  formulation,  and  weir  and  culvert 
coefficients. 

specifies  the  initial  nodal  stages  or  water  elevations  above  the  model  datum. 

specifies  the  upstream  and  downstream  boundary  conditions  (e.g.  stage,  flow,  loop 
rating,  or  stage-discharge). 

time  series  of  stages  or  surface  water  elevations  at  each  head  boundary  node 
specified  in  file  "root.BCI." 

provides  the  time  series  of  flows  or  discharges  at  each  flow  boundary  node  specified 
in  file  "root.BCI." 

contains  daily  meteorological  inputs  such  as  rainfall,  temperature,  solar  radiation  and 
wind  speed  and  direction. 

nodal  head  or  elevation  output  file. 

link  flow  or  discharge  output  file. 

nodal  volume  output  file. 

link  velocity  output  file. 
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When  in  SCREEN  3,  examples  of  the  input  files  may  be  viewed  by  moving  the  cursor  to  the  box  next 
to  the  file  of  choice  and  pressing  the  ENTER  key.  A  sample  input  file  is  displayed  showing  the  ffee- 
field  file  format,  file  delimiters,  and  a  description  of  each  variable  within  a  "Help"  window  at  the 
bottom  of  the  screen.  While  a  sample  input  file  is  being  displayed,  pressing  Control  D  will  display 
brief  information  on  possible  data  sources  for  the  necessary  file  data.  The  "Make  File"  option 
generates  a  file  called  "root"  that  contains  the  file  names  of  all  the  input  and  output  files  required  for 
a  surface  water  module  simulation. 

Note:  While  examining  the  data  structure  for  "root.GRD,"  the  user  can  press  the  Control  F  keys  to 
display  schematics  of  the  geometry  used  to  describe  nodes  or  links.  The  figures  will  be  displayed  in 
conjunction  with  the  appropriate  line  in  the  data  file  "root.GRD." 


VERTICAL  PROCESSES  MODULE  SELECTION:  By  selecting  the  vertical  processes  module  (from 
SCREEN  2)  for  the  model  application,  users  can  simulate  processes  such  as  canopy  interception,  ET, 
and  infiltration.  To  prescribe  inputs  and  boundary  conditions  for  these  processes,  the  following  files 
are  enabled  (i.e.  a  "YES"  will  appear  next  to  the  file  names  on  SCREEN  3). 


root. OUT 
root. PAR 

root.GRD 

root.ELV 

root.NOD 
root. CAN 

root. SOL 

root.INI 

root. MET 

root.HDS 
root.GWH 
root.  SMC 
root.SUM 


general  file  to  which  input  and  run  information  are  output. 

run  parameter  file  where  module  selection;  simulation  start  date,  duration,  time  step; 
print  initiation  and  interval;  and  echo  print  options  are  specified. 

grid  file  where  the  number,  location,  size,  and  shape  of  nodes  and  links  as  well  as 
the  linkage  between  nodes  are  defined. 

bottom  and  overbank  elevations  of  each  node,  and  the  elevations  of  the  bottoms  of 
each  layer  at  each  node. 

canopy  and  soil  types  used  in  each  node  layer  at  each  node. 

canopy  type  in  terms  of  drainage  parameters  and  monthly  values  of  leaf  area  index 
(LAI). 

soil  type  in  terms  of  moisture  parameters,  hydraulic  conductivities,  and  the  power 
function  relationship  to  soil  moisture  tension. 

initial  nodal  water  surface  elevations  and  groundwater  heads  in  each  layer,  with 
respect  to  the  model  datum. 

daily  meteorological  inputs  such  rainfall,  temperature,  solar  radiation,  and  wind 
speed  and  direction. 

nodal  surface  water  head  output  file. 

nodal  groundwater  heads  output  file. 

nodal  soil  moisture  content  output  file. 

vertical  water  mass  balance  file. 
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When  in  SCREEN  3,  examples  of  the  input  files  may  be  viewed  by  moving  the  cursor  to  the  file  of 
choice  and  pressing  Enter.  A  sample  file  will  appear  showing  the  tree-field  file  format,  file 
delimiters,  and  a  description  of  each  variable  within  a  "Help"  window  at  the  bottom  of  the  screen. 
While  the  sample  input  file  is  displayed,  pressing  the  Control_D  keys  will  show  some  general  infor¬ 
mation  on  possible  sources  for  the  necessary  file  data.  The  "Make  File"  option  generates  a  file  called 
"root"  that  contains  the  file  names  of  all  of  the  input  and  output  required  for  a  vertical  processes 
module  simulation. 

HORIZONTAL  GROUNDWATER  FLOW  MODULE  SELECTION:  By  selecting  the  horizontal 
groundwater  flow  module,  users  can  include  that  hydrologic  process  in  their  application.  The  module 
can  be  used  alone  to  simulate  depth-averaged  groundwater  flow,  although  it  is  important  to  remember 
that  the  module  is  based  on  variably  saturated  groundwater  flow  theory.  More  commonly,  the 
module  would  be  used  with  the  vertical  processes  module  (described  above)  to  simulate  three-dimen¬ 
sion  groundwater  flow  and  surface  exchanges.  In  order  to  prescribe  inputs  and  boundary  conditions 
for  these  processes,  the  files  "root.OUT,"  "root.PAR,H  "root.GRD,"  "root.ELV,"  "root. NOD," 
"root.SOL,"  "root.INI,"  "root.GWH,"  and  "root.SMC"  are  enabled  (i.e.  a  "YES"  will  appear  next 
to  the  file  names  in  SCREEN  3)  as  described  above  for  the  vertical  processes  module.  In  addition, 
SCREEN  3  enables  "root.BCI"  which  specified  fixed  head  boundary  conditions  and  the  location  of 
wells. 

MODEL  EXECUTION:  Once  the  necessary  input  data  files  are  created,  the  selected  modules  are 
executed  by  typing  "WWBM"  followed  by  Enter  at  the  DOS  prompt.  (Note:  the  prompt  must  be  in 
the  directory  where  the  swamp  program  resides  or  the  directory  must  be  in  the  PC  Path  [see  DOS 
manual].)  At  the  program  prompt,  enter  the  ’control’  file  name:  "root"  followed  by  Enter.  The 
program  will  echo  the  input  and  output  file  names  and  grid  manipulation  operations  as  they  are 
completed.  During  the  model  simulation,  the  program  prints  a  message  to  the  screen  each  time 
output  data  are  written.  When  "SIMULATION  COMPLETED"  appears  on  the  screen,  execution 
ends. 

OUTPUT  MANIPULATION:  A  post-processing  program  (called  WWBMAID)  is  available  with  the 
water  budget  model.  The  program  allows  users  to  customize  the  output  data  from  the  surface  water 
module  output  files.  After  starting  the  WWBMAID  program,  the  following  data  manipulation 
options  are  displayed: 

1.  Create  file  with  specified  node  numbers 

2.  Compare  computed  and  observed  heads 

3.  Compare  computed  and  observed  flows 

4.  Select  a  node  or  link  for  graphics 

5.  Edit  heads  for  initial  conditions 

6.  Convert  grid  files  to  new  datum  and  units 

7.  Hydroperiod  statistics 

8.  Water  surface  profiles 

9.  Add  more  columns  of  data  to  file 

10.  Groundwater  heads  for  graphics 

1 1 .  Calculate  head  from  soil  moisture  content 

99.  EXIT 

Enter  selection: 
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CONCLUSION:  A  computerized  tutorial  is  available  to  help  users  setup,  calibrate,  and  run  the 
Wed  and  Water  Budget  Model  that  simulates  wedand  hydrologic  and  hydraulic  processes.  The  tutorial 
also  explains  how  to  use  a  post-processing  program  to  manipulate  the  model’s  output  data.  The 
tutorial  program,  the  Wedand  Water  Budget  Model,  and  the  post-processing  program  are  available 
through  the  WES  Engineering  Computer  Programs  Library,  Attention  Gloria  Naylor  at  (601)  634- 
2581.  The  programs’  reference  number  is  722-PD-R0008. 
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